The Complete Clash User Guide, from Beginner to Advanced

Chapter 1

Core concepts: understand the path of a connection

How the client, core, and configuration file work together

The Clash ecosystem usually has three parts: the graphical client handles buttons, configuration management, and system permissions; cores such as Mihomo listen on ports, parse rules, establish proxy connections, and forward traffic; configuration files describe proxies, policy groups, rules, DNS, and TUN parameters. When you click “System Proxy” or “TUN Mode” in the interface, the client is actually changing system network settings and passing the corresponding parameters to the core. Once this relationship is clear, troubleshooting no longer means staring only at the connection toggle. A running status merely shows that the core process has started; it does not prove that the subscription is valid, the right policy is selected, DNS is working, or the target app has entered the proxy path.

The graphical client and the core are not the same version concept. Client updates usually bring interface changes, platform support, and configuration-management features, while core updates focus more on protocols, rule behavior, DNS, and the network stack. Some clients include a core update option; others ship the core with the installer. There is no need to chase every update, but when configuration fields are unrecognized, protocol handshakes fail, or a new operating system causes compatibility issues, check the client and core separately instead of treating them as one “Clash version.”

Traffic entry, policy decisions, and exit

A typical connection can be broken into four steps. First, the browser or app sends its request to the system proxy port, or the TUN virtual interface intercepts it. Second, the core parses the destination domain, IP, process, or network type. Third, rules are matched from top to bottom and send the request into a policy group. Fourth, the policy group chooses a specific proxy node, a direct connection, or a reject action. A break at any step may look like a page that will not load. A disabled system proxy is an entry-point problem, incorrect rule order is a decision problem, an unavailable node is an exit problem, and an abnormal DNS response may occur before the decision stage.

Common listening ports include HTTP, SOCKS5, and mixed-port. An HTTP port suits programs that explicitly support HTTP proxies; a SOCKS5 port suits SOCKS-aware tools; mixed-port accepts both types of requests on one port. Most graphical clients manage these ports for you, so ordinary users do not need to change them. Check the listening address and port only when another program is using the port, LAN devices need access, or a command-line tool requires a manually specified proxy. When listening on 127.0.0.1, only the local machine can connect. Enabling LAN access expands the range of possible clients, so also review the firewall and access controls.

Configuration, subscriptions, and runtime status are different things

A subscription is a remotely maintained configuration source, a configuration file is the concrete content saved locally after download, and runtime status is the result after the core loads a particular configuration. A subscription URL may be reachable while its response does not match the current core syntax; a configuration may parse successfully while its nodes are dead; a node may connect while rules still send the target request directly. Check these layers in order: “Did the subscription update successfully—did the configuration load—does the policy group have selectable options—did the request match the expected rule—is the exit available?” Layered checks are faster than repeatedly toggling the master switch.

After this chapter, remember one principle: connection problems are not controlled by a single switch. Interpret every later setting within the path of “entry, decision, exit.” That keeps the troubleshooting order consistent on Windows, macOS, Android, iOS, and Linux, even when interface labels differ.

Chapter 2

Choose a client: decide by platform, permissions, and maintenance

Start with a graphical client instead of running the core directly

For ordinary desktop and mobile devices, start with a graphical client. It handles configuration storage, the system proxy, startup behavior, logs, core control, and permission requests, making the current state easier to verify when something goes wrong. For all platforms, this site recommends Clash Plus as the first choice for users who want one interface for subscription imports, policy switching, and basic traffic takeover. Windows and macOS users can also choose Clash Verge Rev or FlClash; Windows users may choose Clash Nyanpasu, while the no-longer-maintained Clash for Windows remains available as an archival option; macOS also has the no-longer-maintained ClashX Meta. See the download page for the complete client list, platform links, and current installers.

On Android, choose among Clash Plus, Clash Meta for Android, FlClash, and Surfboard. Pay attention to VPN permission, background limits, and battery-saving policies rather than comparing interfaces alone. On iOS, use the App Store version of Clash Plus; the system takes over traffic through a VPN configuration. Linux desktops can use Clash Verge Rev or FlClash. Servers, routers, containers, and headless devices are better suited to a direct Mihomo deployment managed through configuration files.

Three practical criteria to check

First, check the system architecture. Windows is commonly x64, with a smaller number of ARM64 devices. On Apple-silicon Macs, choose the Apple Silicon or ARM package; older Intel Macs need the x64 package. On Linux, confirm both the distribution format and CPU architecture; AMD64, ARM64, ARMv7, and MIPS packages are not interchangeable. If you are unsure, check system information instead of guessing from the filename. A package that downloads but will not start may indicate an architecture mismatch.

Second, consider which apps need to be covered. If you only proxy browsers and programs that follow system proxy settings, the regular system proxy is usually enough. Games, command-line tools, store apps, virtual machines, and software that ignores system proxy settings may require TUN. Third, consider maintenance. Desktop users usually need visual subscription updates and policy selection; server users care more about configuration files, service processes, remote logs, and automatic restarts. The client with the most features is not automatically the most reliable. Clear update paths, readable logs, and coverage of your actual needs matter more.

Do not let multiple clients take over the system at the same time

You can install multiple clients on one device for comparison, but do not enable their system proxies or TUN modes simultaneously. Two cores may compete for the same listening port, while two clients may repeatedly rewrite system proxy settings, leaving the interface apparently enabled while the port actually points to another process. Before switching clients, disable the old client’s system proxy and TUN, confirm that its process has exited, and then start the new client. If the new client reports a port conflict, identify the process using the port instead of changing to random ports repeatedly; the browser, environment variables, or other tools may still point to the old port.

Archived clients are useful for compatibility with older configurations or temporary migrations, but they are not a good default for a new installation. Lack of maintenance does not make an existing installation fail immediately, but operating-system upgrades, protocol changes, and core field updates can gradually create compatibility issues. Before migrating, export local rules, record policy choices and port settings, and then import the subscription into the new client. Do not copy the entire program directory, which may bring along the old core, cache, and system-integration state.

Chapter 3

Installation and initialization: establish a recoverable baseline

Clear conflicting states before installation

Before installing, quit other proxy clients that are running and disable their system proxy, TUN, or VPN configuration. On Windows, check the system network settings to see whether a manual proxy still points to an old port; on macOS, review the proxy options for the active network service; on mobile devices, check whether another app still owns the VPN shown in the status bar. Keeping an old client installed is fine, but during first-time initialization, let only one program control the network. If the network becomes inaccessible after installation, you can then tell whether the issue comes from the new client rather than overlapping software.

Choose the file according to the operating system and architecture. Windows installers typically place files in the user or program directory through a setup wizard. On macOS, move the app to Applications; the first launch may require confirmation in Privacy & Security. Linux deb or rpm packages must match the distribution, while portable packages and core archives require you to choose a path and set execution permissions. Android asks for VPN permission after installation, and iOS creates a VPN configuration on the first connection after App Store installation. These permissions establish the local traffic entry point; after refusal, the client may open but cannot actually take over the network.

Make only minimal changes on first launch

On the first launch, do not immediately change the port, DNS, TUN stack, or many override settings. Keep the default listening address and port, confirm that the client can start the core, and locate the logs, configuration list, proxy policies, and connection-history views. Then import one valid subscription, select an available policy, and enable the system proxy. Visit an ordinary webpage in the browser and check whether a new request appears in the connection history. If the list does not change at all, traffic has not entered the client; check the system proxy before changing nodes.

If a Windows client needs service mode or a network component, complete the authorization shown in the interface. Service mode is generally used to manage TUN, routing, or system settings with elevated privileges, and may require restarting the client. macOS network extensions and helper services likewise require system approval. In a Linux desktop environment, the tray, system-proxy integration, and TUN permissions depend on the desktop session and system services. When launching a graphical client from a terminal, check whether closing the terminal also terminates the process.

Verify installation through observable signals

Installation is not successful merely because a window appears. Confirm at least four signals: the core log is not repeating startup errors; a local listening port has been created; the subscription configuration loads; and, after enabling the system proxy, browser requests appear in the connection history. If the log says the address is already in use, use netstat on Windows or lsof on macOS and Linux to identify the process using the port. The commands below only inspect local listening status and do not modify network settings:

Windows:
netstat -ano | findstr LISTENING

macOS / Linux:
lsof -nP -iTCP -sTCP:LISTEN

If an old client owns the port, quit the relevant process first and restore any system proxy settings it changed. If no port is listening but the client says it is running, open the core log and look for configuration parsing errors, insufficient permissions, or a missing core file. Do not begin by disabling the firewall or security settings. Follow clear log evidence first: failure to create a local loopback port and a blocked remote connection are different problems with different fixes.

Mobile verification also needs to account for background restrictions. If Android disconnects after the screen turns off, common causes include battery optimization, background-activity limits, or system process cleanup. Allow the client to run in the background and confirm that the VPN remains active. On iOS, switching between Wi-Fi and cellular data may rebuild the network and cause a brief reconnect; that is normal system behavior. If it does not recover, return to the client to inspect the current configuration and policy instead of repeatedly deleting the VPN configuration.

Preserving this minimal working state matters. After enabling rule overrides, TUN, or DNS, you can return to “default configuration plus system proxy” one change at a time if the network becomes unstable. Changing several modules at once may save steps, but it makes the cause impossible to isolate and often leads to reinstalling. Reinstallation does not automatically remove system proxy settings, services, or local configuration.

Chapter 4

Subscriptions and configuration: update sources, load results, and local changes

First checks after importing a subscription

Subscriptions are usually imported through a URL, the clipboard, or a local file. After adding one, run a manual update and confirm that the client shows an update time and that the proxy-policy page contains nodes and policy groups. Seeing a subscription name does not mean its content downloaded successfully; an expired URL, inaccessible network, invalid response format, or incompatible conversion result can leave an empty configuration entry. When an update fails, check the HTTP status, parsing message, and save path in the client log instead of clicking Update repeatedly.

A subscription URL often contains access credentials, so protect it like an account password. Do not include it in public screenshots, support threads, or log attachments. When changing devices, obtain the URL again through a trusted channel rather than repeatedly copying it from browser history or chat logs. Also distinguish export sources: a full export may contain the subscription URL and node parameters, while exporting only local rules or overrides is better for migrating personal settings.

The boundary between remote configuration and local overrides

Directly editing the YAML downloaded from a subscription is usually not a long-term solution. The next update may overwrite the local file, removing manually added rules, DNS settings, or policy groups. In clients that support overrides, merging, or extension scripts, keep personal rules in a separate override layer. Without override support, you can copy the subscription into a local configuration, but it will no longer automatically follow remote changes. Before maintaining a configuration, determine whether the client uses “replace on update,” “merge on update,” or “generate a runtime configuration”; otherwise, changes made in the interface may disappear after a restart.

Standard YAML uses indentation to express hierarchy and must not mix tabs with spaces. List items begin with hyphens, and strings containing colons, hash signs, or special characters should preferably be quoted. When configuration loading fails, the error may point to a later line even though the real cause is an indentation problem or an unclosed quote on the previous line. Test small changes one at a time and keep the last loadable file. The following minimal example is for understanding structure; the server address is reserved for documentation and cannot be used for a real connection:

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

proxies:
  - name: "Example Node"
    type: socks5
    server: 192.0.2.10
    port: 1080
    username: "demo-user"
    password: "your-password"

proxy-groups:
  - name: "Manual Select"
    type: select
    proxies:
      - "Example Node"
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,Manual Select
  - MATCH,DIRECT

Names in the configuration must match. If a rule points to “Manual Select,” a policy group with the same name must exist. If a policy group refers to “Example Node,” the node name must match exactly, including spaces and capitalization. Common loading errors are not caused by protocol parameters themselves, but by renaming a node without updating the policy group or copying a rule that refers to a group absent from the configuration. Non-English names work, but short, stable names are easier to maintain across tools.

A layered approach to subscription update failures

First confirm whether the device can reach the subscription URL without relying on that subscription configuration. Sometimes an expired old configuration also prevents updates; temporarily disable the proxy for a direct update, or switch to another working configuration. If the response is a webpage, login page, or error message rather than configuration content, handle authorization with the subscription provider instead of saving the page as YAML. If the download succeeds but parsing fails, check whether the subscription targets another client format or contains fields unsupported by the current core.

Subscription conversion should be treated as configuration generation, not node repair. Conversion can reorganize policy groups, rules, and fields, but it cannot revive dead nodes or change the subscription’s permissions. When using a converter, record the template source, target format, and update method so you can explain where a rule came from months later. For access credentials, verify the processing path and storage location, and complete the work in an environment you control whenever possible.

The goal of configuration management is not to keep as many files as possible, but to know which one is running, where it updates from, and what was added locally. Give local configurations clear purposes such as “Daily desktop,” “System proxy test only,” or “TUN troubleshooting,” and remove duplicate copies that are no longer used. With too many configurations, selecting an old file by mistake is often harder to notice than a rule problem.

Chapter 5

Proxy modes: choosing between rules, global routing, and direct connections

Rule mode is the everyday default

Rule mode evaluates requests against the configured rules and decides whether to send them to a policy group, connect directly, or reject them. It suits long-term use because different websites and apps can use different exits, while local services, LAN addresses, and traffic that needs no proxy can remain direct. Whether rule mode behaves as expected depends on rule content and order, DNS results, and policy-group selection. It is not a black box that automatically understands every network environment. When an address takes the wrong route, inspect the matched rule in the connection details instead of leaving the entire client in global mode.

Connection history usually shows the destination domain or IP, matched rule, policy chain, and final node. To troubleshoot one website, clear or filter the connection list, make the request again, and inspect the new connection. A browser may request the main domain, static assets, login APIs, and third-party services at the same time, so a broken page may not be caused by its main domain. Only after locating the failed connection and its matched rule can you tell whether the issue is a missing rule, wrong policy selection, or an unavailable node.

Use global mode to isolate rule problems

Global mode generally sends most intercepted traffic to a specified policy or node, making it useful for a short exit-path test. If a website works in global mode but not in rule mode, the node can connect and the problem is more likely in rule matching, DNS, or the policy-group path. If global mode also fails, check the node, protocol, system time, and network environment first. Global mode is a diagnostic tool and can temporarily provide a uniform exit, but it bypasses the original routing design and may affect LAN, local services, and traffic that does not need a proxy.

After switching to global mode, confirm what the global policy group is using. Some configurations expose “GLOBAL” as a selectable list that still requires a node to be chosen manually; changing the mode alone without selecting a valid exit may produce the same result as rule mode. Return to rule mode after testing and reopen the target app. Some programs reuse existing long-lived connections, so switching modes does not immediately change the route of an old connection. Close the relevant browser tabs or wait for the connection to be rebuilt.

Use direct mode to verify the local network

Direct mode sends intercepted requests straight to their destinations without using a proxy node. It helps determine whether the basic network, DNS, and target service are reachable from the current network, and it can keep the client running while the proxy is paused. Direct mode is not the same as disabling the system proxy: traffic may still enter the core, with DIRECT as the final action. To exit the client completely, disable the system proxy or TUN and confirm that system network settings have been restored.

If ordinary websites are also unreachable in direct mode, the problem may be the local network, DNS, system routing, firewall, or another VPN that is still active. Changing proxy nodes will not help. Conversely, direct works but global fails usually points to the node or proxy protocol; direct and global work but rules fail points to rules or policy groups. This three-mode comparison quickly narrows the scope, but each test should use the same target, network, and new connection to avoid cache effects.

The policy group determines the final exit

The mode only determines how traffic enters policy evaluation; the policy group determines which exit is actually used. Common policy-group types include manual selection, automatic latency testing, fallback, and load balancing. Manual selection is easiest to understand and suits important scenarios. Automatic testing chooses a better-performing node based on a test URL and interval, but test latency is not the same as real browsing speed. Fallback switches to a backup when the current node is unavailable and is better for configurations that prioritize continuity. Client labels may differ, so use the type in the configuration as the authority.

Automatic selection cannot replace real-world verification. A reachable test URL only proves that the node can complete that test request; the target website may use a different route, protocol, or regional policy. If latency looks normal but pages are slow, inspect connection establishment time, download behavior, and packet loss, and compare a small number of nodes manually. Very short test intervals create extra background requests and may make the policy switch repeatedly between nodes. For everyday use, choose a sensible interval and retain manual selection for important policies.

Chapter 6

Rule routing: match order, rule types, and overrides

Rules match from top to bottom; the first match wins

The most important behavior of Clash rules is their order. Requests are checked from the top of the list, and the first matching rule determines the policy; lower rules are not evaluated. Specific domain rules should generally come before broad domain suffixes, GeoIP rules, or the final catch-all. If a broad rule matches first, a later precise rule will never run, even if it is written correctly. When a custom rule appears ineffective, check the actual matched rule in the connection history before comparing its position in the list.

Common rules include DOMAIN for exact domains, DOMAIN-SUFFIX for domain suffixes, DOMAIN-KEYWORD for domain keywords, IP-CIDR for IPv4 networks, IP-CIDR6 for IPv6 networks, GEOIP for geographic IP categories, PROCESS-NAME for process names, and the final MATCH. Domain rules are most direct while the domain is visible; IP rules depend on resolution results; process rules depend on the platform and traffic-capture method, and not every system or client can identify processes consistently.

Write from precise conditions to broad fallbacks

When adding a rule, define the target first: one host, an entire domain suffix, an IP range, or an application process. If an exact domain solves the problem, do not use an overly broad keyword; it may affect unrelated domains containing the same text. A domain-suffix rule covers the root domain and its subdomains, making it suitable for stable service structures. IP-range rules suit services without domain information or those intentionally routed by address, but CDN and regional changes can alter addresses, so they require maintenance.

rules:
  - DOMAIN,api.example.com,Work Policy
  - DOMAIN-SUFFIX,example.net,Manual Select
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Manual Select

no-resolve tells the core not to perform an extra domain lookup merely to evaluate an IP rule, which suits explicit address conditions such as private ranges. Whether to add it depends on the rule type and actual need; do not append it mechanically to every rule. MATCH is the final fallback and normally belongs at the end. Requests that match nothing above it enter its specified policy. If MATCH appears in the middle, later rules never get a chance to run.

Rule sets and Geo data must be traceable

Large configurations commonly reference rule sets through rule-providers instead of embedding thousands of rules in the main file. Rule sets are easier to update independently, but they introduce three variables: source, behavior, and update time. Before using one, know what category it covers, which format it uses, which policy references it, and whether cached data remains active after an update failure. Avoid stacking several heavily overlapping rule sets; the matching source then depends on order and becomes difficult to explain later.

GeoIP and geographic site classification depend on local data files. When data is stale, newly assigned addresses or new domains may be classified incorrectly; when downloads fail, the client may continue using an old cache. For Clash GeoIP updates, first check whether the client provides a data-update entry, then verify successful download and loading in the logs. If routing changes suddenly after an update, compare the matched rules before and after instead of inferring IP classification from the site's content or company location.

Place local overrides at the right insertion point

Client labels such as “prepend rules,” “append rules,” and “merge rules” may mean different things. Prepend rules are usually inserted before remote rules and suit personal rules that must match first. If append rules are placed after a remote MATCH, they will effectively never apply. When using overrides, inspect the final generated runtime configuration or the rule order in the logs and confirm that custom content appears before MATCH. Seeing a rule in an editor does not prove that the core loaded it in the same position.

Start rule debugging with one target. Clear the connection filter, visit the target domain, and record the domain, resolved IP, matched rule, policy group, and final node. Then change only one rule, reload the configuration, and create a new connection. Browser DNS caches, connection reuse, and service workers may preserve the old path; close the relevant page or restart the target app if necessary. For more syntax and override examples, continue with Clash Custom Rule Syntax Explained.

Chapter 7

TUN and DNS: capture more traffic with consistent resolution

System proxy and TUN cover different traffic scopes

The system proxy mainly affects apps that read the operating system’s proxy settings. Browsers and some desktop software support it well, but games, command-line tools, store apps, virtual machines, and software with its own network stack may bypass it. TUN creates a virtual network interface and uses system routes to pass more IP traffic to the core, so its coverage is broader. It is not a “faster system proxy” but a different entry mechanism, bringing its own routing, DNS, permission, LAN, and VPN compatibility issues.

Before enabling TUN for the first time, make sure system proxy mode works. This demonstrates that the subscription, node, and basic rules are broadly valid, narrowing a TUN failure to permissions, the virtual interface, routes, or DNS. If you enable TUN, custom DNS, IPv6, and several overrides at once, a network outage becomes difficult to attribute. Start by disabling the system proxy and testing with default TUN parameters; once requests appear in the connection history, adjust DNS and bypass rules one at a time.

Permissions, routing, and network-stack parameters

TUN creates a virtual interface and changes system routes, so desktop systems usually require administrator privileges, a helper service, or a network extension. On Windows, check service mode, driver status, and other VPNs; on macOS, approve the network extension; on Linux, provide the TUN device and the required capability or administrator permission. Insufficient permissions usually produce interface-creation, route-setup, or device-access errors in the log. Changing nodes repeatedly will not change this result; fix system permissions first.

Common TUN stack names include system, gVisor, and mixed, but available values depend on the core and client. system relies more heavily on the operating system network stack, gVisor handles more networking in user space, and mixed combines handling by protocol. Keep the client default when there is no specific problem. If a particular app cannot connect, UDP behaves abnormally, or networking fails after sleep and wake, record the original value before comparing stacks. Change one item at a time and restart the core so the virtual interface is recreated.

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

auto-route automatically writes routes, while auto-detect-interface identifies the current default network interface. When a device has wired networking, Wi-Fi, virtual-machine adapters, and another VPN connected at once, automatic detection may choose the wrong exit; the usual symptom is that every connection times out after TUN is enabled. Quit other network tools, re-enable TUN, and observe the default interface. strict-route enforces tighter routing constraints and may reduce bypasses, but it can also affect LANs, virtual machines, and special routes. Do not enable it blindly in a first configuration.

DNS mode determines how domains enter rule matching

DNS does more than convert domains into IP addresses. It also affects whether rules can see the domain, which exit a connection uses, and whether resolution paths diverge. Common enhanced Clash DNS modes include redir-host and fake-ip. redir-host is closer to returning the real resolution result; fake-ip first returns a mapped reserved address, then restores the domain during connection handling, keeping domain information available for rule matching. Some LAN services, device discovery, games, and programs that require real IPs may need to be added to fake-ip-filter.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 1.1.1.1
    - 8.8.8.8
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "time.*.com"

The public resolvers in examples only demonstrate syntax. Choose actual resolvers according to the local network, configuration rules, and privacy requirements. If the configuration separates DNS paths for proxy and direct traffic, ensure that the resolver used for proxy target servers does not itself depend on a proxy that has not been established, avoiding a startup loop. When concerned about a Clash DNS leak, do not rely on one test website. First confirm whether TUN or DNS hijacking captures system DNS requests, then inspect the core log, listening port, and actual resolver destination. Browser-encrypted DNS may also bypass the system path and must be checked.

Handle TUN failures by restoring connectivity first

If enabling TUN cuts off all networking, disable TUN first and confirm that routes recover. If connectivity is still unavailable, exit the client and check for leftover virtual interfaces, proxy settings, or other VPNs. Restart the client and use only the system proxy to verify the basic connection. Once that works, inspect TUN logs for interface creation, the default route, DNS listening, and permission errors. If LAN devices are unreachable, check that private ranges remain DIRECT, strict routing is not blocking them, and LAN addresses are not being handled by fake-ip.

Network loss after sleep and wake, switching Wi-Fi, or moving from wired networking to a hotspot is often caused by changes to the default interface and routes. Wait for the client to rebuild them automatically; if it does not recover, disable and re-enable TUN. If this happens often, check whether the client supports reloading after network changes and inspect auto-detect-interface. When containers, virtual machines, or remote-access tools are also running, record the networks they create so TUN routes do not override them. TUN is stable only when network changes, sleep recovery, and LAN access all produce explainable results—not merely when its toggle lights up.

Chapter 8

Everyday maintenance and Troubleshooting: start with configuration validity

Establish a lightweight maintenance routine

Daily maintenance does not require changing the configuration. A more reliable routine is to update subscriptions and rule data periodically, then perform a minimal check: does the configuration load, do common policy groups have nodes, can an ordinary webpage open in rule mode, and does the connection history look right? Before updating the client or core, record the current configuration, TUN state, port, and local overrides. Afterward, verify the basic connection first, then restore complex options. If stability matters, you can delay feature updates, but check maintenance status after an operating-system upgrade or a protocol compatibility issue.

Back up locally added content rather than cache files. Save how the subscription source was obtained, local override rules, DNS changes, policy-group edits, and service configuration. If the node list is generated entirely by the subscription, there is no need to keep many snapshots; preserve the personal settings that cannot be recreated from the subscription. Label backups with their purpose and date, and do not expose subscription URLs, node credentials, or LAN details.

A fixed order for “connected but offline”

First, check whether the configuration loaded and whether policy groups contain available options. Second, switch to direct mode to verify the local network, then switch to global mode and select a specific node to rule out routing rules. Third, confirm that the system proxy or TUN is actually capturing traffic: if the connection history shows no new requests, the problem is at the entry point; if requests appear and fail quickly, inspect the rules, policy chain, and error type. Fourth, check DNS by comparing domain access with direct IP access. Fifth, check port conflicts, TUN permissions, other VPNs, the firewall, and system time.

“Connected” often means that the node handshake completed or the client is running; it does not mean every destination is reachable. If only one website fails, inspect its multiple domains and matched rules first. If every website fails, check the exit and system network. If the browser works but the command line does not, confirm whether the command-line tool reads the system proxy or set proxy environment variables for the current terminal. For a temporary test, use the local mixed-port shown by the client:

Windows PowerShell:
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

macOS / Linux:
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

Environment variables apply only to the current terminal and processes launched from it, and usually disappear when the terminal closes. If the client does not use port 7890, replace it with the actual value. After testing, do not accidentally place temporary variables in the global shell configuration, especially on devices where the client is not always running; otherwise command-line tools will keep pointing to a nonexistent port. For a fuller step-by-step process, see Clash Connected but Offline: Troubleshooting Checklist.

Separate latency, timeouts, and speed problems

Clash node latency tests usually send a small HTTP request, and the result depends on the test URL, DNS, handshake method, and current network. Low latency does not mean high download speed or guaranteed access to the target service. A timeout may result from an unreachable node, a blocked test URL, a failed protocol handshake, or local packet loss. Compare nodes using the same test URL at roughly the same time, and consider real browsing or download behavior instead of relying on one sort order.

When speed suddenly drops, first determine whether only one destination is affected, then compare direct mode, global mode with different nodes, and rule mode. Check whether connections are using the expected policy, whether the node is switching frequently, and whether a subscription or rule update is running in the background. Unstable Wi-Fi, power saving, mobile-network changes, and other downloads also affect results. If the issue appears only at night or on a particular route, it may be a network-path change; reinstalling the client repeatedly usually will not help.

Collect only the log window around the problem

During troubleshooting, temporarily set the log level to info or debug, reproduce the problem once, and record the time, target, mode, and error line. Debug logs are verbose and are not suitable for long-term use or unprocessed public sharing. Before sharing, remove subscription URLs, node servers, authentication data, local usernames, and file paths. Useful logs include startup, DNS, rule-matching, and connection errors immediately before and after the incident, not just the final “timeout” line.

For HTTPS certificate errors, first check system time, browser policy, the system certificate chain, and network intermediaries before deciding whether the proxy path is involved. Ordinary Clash forwarding does not require installing a decryption certificate for every website. If an app enables traffic inspection, script rewriting, or another intermediary process, investigate that separately. Follow How to Handle HTTPS Certificate Errors After a Proxy layer by layer instead of bypassing the problem by ignoring certificate warnings.

Chapter 9

Advanced Configuration: from stable setups to maintainable setups

Turn personal needs into verifiable conditions

Advanced Configuration is not about stacking more rules and toggles. It is about turning needs into behavior you can verify. Examples include “work domains always use a fixed policy,” “LAN and development environments stay direct,” “TUN recovers automatically after a mobile-network change,” and “cached rules remain available when a rule-set update fails.” Each goal should have a configuration, an observation method, and a rollback plan. If you cannot explain what an override solves, leave it out of the long-term configuration.

Create a baseline configuration and an experimental configuration. The baseline should contain only a stable subscription, clear policy groups, necessary rules, and verified DNS/TUN parameters. Use the experimental configuration to test new rule sets, network stacks, or policy behavior. Move each successful change into the baseline individually. If parsing fails or routing breaks, you can quickly return to a working state instead of guessing among many historical edits.

Manage dynamic nodes with proxy-providers

When node sources are maintained separately from the main configuration, use proxy-providers to define remote or local providers and let policy groups reference them. Policy groups and rules can then remain stable while the node list updates on schedule. Define each provider’s type, path, update interval, and health check clearly. Avoid sharing one cache path among multiple providers, and choose a health-check target that is stable, lightweight, and representative of the real network.

proxy-providers:
  primary:
    type: http
    url: "https://example.com/subscription"
    path: "./providers/primary.yaml"
    interval: 21600
    health-check:
      enable: true
      interval: 900
      url: "https://www.gstatic.com/generate_204"

proxy-groups:
  - name: "Automatic Select"
    type: url-test
    use:
      - primary
    url: "https://www.gstatic.com/generate_204"
    interval: 600

The example address only illustrates the structure. Actual subscription URLs should come from a reliable source and be stored securely. A shorter update interval is not automatically better: it creates more remote requests and local reloads, while frequent node changes may interrupt long-lived connections. A health check also does not prove complete usability; it only shows that the node can reach the test target. Keep a manual policy group for important traffic and use automatic selection as a candidate when appropriate, not the only exit.

Split rule responsibilities with rule-providers

As the rule count grows, split rules by purpose into sets such as LAN, work, media, development, direct, and block. Keep only reference order and the final policy in the main configuration so each set has a clear responsibility. Avoid creating overly granular files for individual websites, which merely shifts maintenance into a large number of small files. More useful boundaries are rules with the same update source, policy target, and maintenance cycle.

Before updating a remote rule set, retain its cache and confirm that the format matches the behavior type. domain, ipcidr, and classical rule sets use different content structures; an incorrect type can cause parsing failures or unexpected matching. After a rule set loads successfully, verify representative targets through the connection history. A successful download alone does not prove correct rule order or that traffic entered the expected policy.

Core deployments need service and permission management

When running Mihomo directly on a server or router, you must handle the work a graphical client normally does: configuration paths, the working directory, logs, process supervision, startup order, updates, and permissions. First load the configuration with a foreground command and confirm that there are no syntax errors, then hand it over to the system service manager. Do not start with a silent background process, or startup failures will be difficult to diagnose. Relative paths in the configuration are based on the working directory; if the service manager uses a different directory from manual testing, rule sets and database files may not be found.

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

The first command checks the configuration; the second sets the working directory and loads the file. Use the executable name and path provided by the download. The service account should be able to read configuration, write caches, and create required network interfaces, but do not grant unnecessary write access to the entire configuration directory for convenience. After a configuration change, run the check before reloading the service. If a remote device relies on the proxy for administration, prepare a local console or rollback path before updating.

Expand in stages instead of enabling everything at once

The advanced path can be divided into four stages. First, use rule mode reliably and explain a request through the connection history. Second, organize local overrides and rule sets so subscription updates do not overwrite personal settings. Third, enable and stabilize TUN, DNS, and network-change handling. Fourth, consider providers, server deployment, automatic updates, and monitoring. Run each stage for a while and confirm that everyday networking, sleep recovery, LAN access, and common apps remain stable before moving on.

During learning, record symptoms and conclusions instead of collecting large numbers of unverified configuration snippets. The default value of the same field may differ across cores, clients, and operating systems, so verify the active runtime configuration before copying it. For Windows system proxy, subscription, and UWP loopback issues, see The Complete Windows Clash Installation Guide. To review first-time initialization, return to Clash First-Install Setup Checklist.

Use the same process for every later change: define the goal, back up the baseline, change one item, reload, inspect the logs and connection history, then compare direct, global, and rule modes. When replacing or reinstalling a client, visit the Clash client download page to confirm the platform and architecture. When you only need to restore the first connection quickly, follow the Getting Started tutorial to rebuild the minimal state. The purpose of a system guide is not to make setup more complicated, but to give every toggle a clear place and every failure a consistent starting point.