REFERENCE / ZERO TO PRO

Clash Desktop
From Setup to Mastery

Build a complete understanding in the order of core concepts, client installation, subscriptions, proxy modes, rules, TUN, and maintenance. Use this page as a reference; if you only need to connect once, start with the quickstart guide.

01

TRAFFIC MODEL

Core Concepts: See What a Connection Passes Through

Clash is not a simple “on/off” switch. It is a local traffic-processing chain. An application sends a connection to a local listening port or virtual network interface. The Clash core reads the target domain, destination IP, network protocol, and process information, then matches rules from top to bottom in the configuration before sending the connection to DIRECT, a proxy group, or REJECT. Understanding this path matters more than memorizing client buttons. If the system proxy is enabled but an application still connects directly, a node tests successfully but a page will not load, or Rule and Global behave differently, the cause usually lies somewhere along this chain.

Clients, Cores, and Configuration Files

The desktop client handles the interface, profile management, system proxy switch, logs, and updates. Compatible cores such as Mihomo handle listening ports, rule parsing, and connection forwarding. YAML configuration files describe ports, DNS, proxy nodes, proxy groups, and rules. Keep these roles separate. Changing the client does not necessarily change configuration syntax; whether a profile works mainly depends on core support for its fields and the client’s import method. A client starting normally does not prove that the subscription, DNS, or system proxy is configured correctly.

Common local ports include an HTTP proxy port, a SOCKS5 port, and a mixed-port that accepts both protocols. Desktop clients usually manage these values automatically. With mixed-port: 7890, a browser or terminal can use 127.0.0.1:7890 as its proxy address and send traffic into the core. external-controller is a control interface used by the client to read connections, switch proxy groups, or load profiles. It should not be confused with a proxy port.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: true
external-controller: 127.0.0.1:9090

The Boundary Between System Proxy and TUN

A system proxy is a set of HTTP or SOCKS proxy settings exposed by the operating system. Browsers and most desktop software read them, but terminal commands, games, some store apps, virtual machines, and applications with their own network stack may ignore them. TUN creates a virtual network interface and captures IP traffic at a lower layer, usually covering more applications. Neither is a speed setting, and they do not have to be enabled together. Use the system proxy for everyday browsing; evaluate TUN only when an application clearly ignores the system proxy.

Domains, DNS, and Rule Matching

After a user enters a domain, DNS converts the name into an IP address. The rule engine may match the domain before resolution and may continue with GEOIP or IP-CIDR rules after an IP is available. If DNS requests take the wrong network path, pages may fail to load, rules may not match as expected, or local domains may stop working. “The node works but the site does not” is often caused by DNS resolution, IPv6, the browser’s secure DNS, or rule order rather than by the proxy node itself.

The log and connections pages are two ways to observe this chain. Logs show whether the profile loaded, whether a port is occupied, and whether DNS reported an error. The connections page shows which applications created sessions, their destinations, matched rules, and final policies. When using a client for the first time, read the client interface overview to understand the roles of the proxy, profile, connections, and logs pages. Once these concepts are clear, installation, subscriptions, and rule editing become deliberate operations rather than mechanical clicks.

02

CLIENT AND INSTALLATION

Client Choice and Installation: Match the Platform First

Desktop options include Clash Plus, Clash Verge Rev, FlClash, Clash Nyanpasu, Clash for Windows, and ClashX Meta. Mobile options also include Clash Meta for Android and Surfboard. The download list on this site recommends Clash Plus across platforms because it supports Windows, macOS, Android, and iOS with a similar workflow. For community desktop clients, compare Clash Verge Rev, FlClash, and Nyanpasu. Clash for Windows and ClashX Meta are no longer maintained; use them only for legacy environments or existing profiles, not as the default for a new installation.

Platform Preferred Choice Install Format Check Beforehand
Windows Clash Plus Installer System architecture, security prompts, UWP loopback, and service permissions
macOS Clash Plus Apple Silicon or Intel installer Chip architecture, app approval, and network-extension permissions
Linux Clash Verge Rev DEB or RPM Distribution package format, desktop environment, and service permissions
Android Clash Plus APK CPU architecture and system VPN authorization
iOS Clash Plus App Store VPN configuration authorization on first launch

Windows: Architecture, Install Location, and Loopback Limits

Most Windows computers use an x64 installer. ARM devices need a package explicitly built for ARM; do not mix architectures just because the system interface looks the same. After installation, launch the client normally and confirm that the tray icon, profile page, and logs open before importing a subscription. If Windows asks you to approve an app from the internet, verify the download source and filename, then follow the system process. Do not disable all security features to bypass a single prompt.

After enabling the system proxy, traditional desktop browsers usually work directly. Some UWP apps are affected by Windows loopback isolation and cannot reach a local proxy port. Use the UWP loopback tool supplied by the client and add only the applications that need proxy access, then restart the target app. Loopback settings solve “the app cannot connect to the local proxy”; they do not repair an expired subscription, an invalid node, or incorrect DNS. For the full platform workflow, see the complete Windows Clash installation guide.

macOS: Chip Architecture and Network Permissions

Check whether the processor is Apple Silicon or Intel in About This Mac, then choose the matching installer. With the wrong architecture, the app may fail to launch or require an extra compatibility layer. The first time you enable the system proxy, service mode, or TUN, macOS may request administrator credentials and approval for a network extension. Complete the authorization through the system dialog. Do not move the client out of the Applications folder and continue running it, or login items and helper-service paths may stop working.

Linux: Package Formats and Desktop Sessions

Debian, Ubuntu, and derivatives generally use DEB; Fedora and RHEL-based distributions generally use RPM. If the menu entry does not appear immediately after installation, restart the desktop session or launch the app once from a terminal to see the exact error. Linux desktop environments do not implement system proxies identically. Browsers may read GNOME or KDE proxy settings, while terminal tools usually depend on environment variables. Configure TUN for full capture only when necessary, after confirming that the system can create a virtual interface and modify routes.

# Debian / Ubuntu: install a local DEB package
sudo apt install ./client-package.deb

# Check whether common ports are occupied
ss -lntp | grep -E '7890|9090'

If you are still comparing clients, read the comparison of Clash Plus, Verge Rev, and FlClash. Prioritize current platform support, TUN implementation, profile compatibility, and maintenance status over the number of interface elements. Once decided, use the download center for the relevant platform instead of mixing installers and instructions from different sources.

03

PROFILE AND SUBSCRIPTION

Subscriptions and Profiles: Create a Recoverable Source

Clash profiles are usually YAML files. A complete profile may contain proxy nodes, proxy groups, rules, DNS, TUN settings, and listening ports. A subscription URL is a remote source; the client downloads its content and saves a local profile. After import, the core reads the local copy. Updating the subscription fetches the remote content again, so direct edits to a generated profile may be overwritten during the next update.

Identify What You Have First

A subscription URL that can be imported from a browser address bar, a generic subscription containing encoded text, and a YAML file with proxies:, proxy-groups:, and rules: are different delivery formats. When the client reports a format error, inspect the returned content before clicking Import repeatedly. If the server returns a login page, an expiration notice, or a generic Base64 node list, the client may save it but cannot load it as a complete Clash profile.

Valid YAML is indentation-sensitive and uses spaces rather than tabs. Keep indentation consistent at each level, begin list items with hyphens, and quote names containing colons, hash signs, or special characters. When copying from a browser, avoid full-width punctuation and smart quotes. For the difference between YAML, Base64, and format conversion, read Clash subscription formats and conversion methods.

mixed-port: 7890
mode: rule
log-level: info

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

  - name: "Auto Select"
    type: url-test
    proxies:
      - "Example Node A"
      - "Example Node B"
    url: "https://www.gstatic.com/generate_204"
    interval: 300

rules:
  - DOMAIN-SUFFIX,example.com,Node Select
  - GEOIP,CN,DIRECT
  - MATCH,Node Select

Import, Activate, and Update Are Different Actions

Import adds a subscription or file to the client’s profile list. Activate selects one profile for the core to run. Update fetches its remote content again. Paste the subscription URL on the profile page and confirm that the download finishes; select that profile, choose the proxy-group policy on the proxy page, and then enable the system proxy. If several profiles exist, identify the active one so you do not edit profile A while profile B is running.

When a subscription update fails, follow the HTTP request chain. First confirm that the URL has not expired and is reachable on the current network. Then check the system clock, since clock drift can break TLS connections. Finally inspect status codes and parsing errors in the client logs. A 401 or 403 usually indicates authorization or link status; HTML often means the address points to a web page rather than profile content; a parsing error calls for checking YAML structure and core compatibility. Never post a complete subscription URL in a forum or screenshot because it may contain access credentials.

Overwrite Risks and Local Extensions

To add custom rules, prefer the client’s override, profile merge, script-extension, or rule-set features. This separates service-maintained nodes from local rules. If merging is unavailable, copy the subscription into a local file and edit the copy while keeping the original subscription for updates and comparison. After an update, merge node and proxy-group changes into the local copy. This is easier to recover than editing an automatically updated file.

When a profile fails to load, the line number in the log usually marks where the parser noticed the problem, while the actual indentation error may be several lines earlier. Check matching fields, closed quotes, and list indentation above the reported line. If the profile loads but the proxy group is empty, verify that names referenced by proxy-groups exactly match names in proxies. A node that exists but cannot be selected may indicate a group type issue, a provider reference, or an incomplete conversion result. Record “download failure,” “parse failure,” and “runtime failure” separately.

04

ROUTING MODES

Proxy Modes: What Rule, Global, and Direct Change

The common Clash modes—Rule, Global, and Direct—control how the core chooses a final policy. They do not determine whether an application sends traffic to Clash, and they do not repair an unavailable node automatically. If the system proxy is off, a browser connection that never reaches the local port will not use the core even in Global mode. If TUN has captured the traffic, switching modes affects only captured connections. Mode selection must therefore be understood within the complete traffic path.

Rule: Decide One Rule at a Time

Rule is the normal default. The core checks rules from the top and stops at the first match. Local networks and explicitly direct domains may use DIRECT, domains requiring a proxy may enter a proxy group, unwanted destinations may use REJECT, and the final MATCH rule handles everything else. Rule mode keeps access scope, network paths, and local-service compatibility balanced instead of sending all traffic through one exit.

Global: Centralize the Choice in One Group

Global mode usually sends every connection that has entered the core to the global proxy group. It is useful for testing whether rules are responsible for a failure. If a site fails in Rule but works in Global, the node and basic proxy path are probably working; inspect rule matching, DNS, or proxy-group selection. If both fail, check the node, port, system proxy, and DNS first. Global is not a good permanent substitute for fixing incorrect rules because local services, LAN devices, and traffic that needs no proxy may also be sent through the proxy.

Direct: Connect Captured Traffic Directly

Direct makes connections that reach the core access their destinations directly. It can show whether capture itself is causing a problem and can temporarily disable proxying while leaving the core running. Direct does not fully exit the client: local ports, TUN, DNS modules, and connection records may continue operating. To restore the original system path, disable the system proxy or TUN, exit the core, and confirm that the operating system proxy settings have been restored.

Mode Decision Method Use Case What It Cannot Prove
Rule Match the rule list Everyday routing with LAN and proxy traffic One failed visit is not necessarily a node failure
Global Use one global policy group Check whether rules are causing the issue It does not prove every app reached the core
Direct Connect everything directly Test capture and restore local access It does not mean system proxy and TUN are off

Proxy Groups Are Closer to the Actual Exit

The mode determines where the core looks for a policy; the proxy group decides which node or subgroup is actually used. A select group is chosen manually. A url-test group periodically measures a test URL and selects an available candidate. A fallback group uses available nodes in order. load-balance distributes connections according to its implementation and strategy. A test result reflects connectivity to the test URL, not every destination or sustained bandwidth.

Existing TCP, QUIC, or long-lived connections do not necessarily move to a new node after switching. Browsers may reuse old connections, and applications may retain DNS caches. To verify a switch, close related sessions on the connections page, reopen the target application, and wait for old sessions to expire if needed. If a rule sends the destination to another proxy group, switching the currently highlighted group will not change the result. Check the rule and chain on the connections page instead of watching only the proxy page.

Switch modes to test a hypothesis, not at random. After each change, record the destination domain, matched rule, actual policy, and connection result. This quickly separates rule issues from link issues. For everyday use, return to Rule and fix a small number of exceptions with custom rules; it is more controllable than leaving Global enabled.

05

RULE ENGINE

Rule Routing: Match Order and Custom Rules

Rules run from top to bottom, and the first match determines the connection policy. The rule system does not calculate a combined score or automatically choose the most specific rule. If a broad DOMAIN-SUFFIX, GEOIP, or IP-CIDR appears first, an exception written later may never run. Use the structure “specific exceptions first, broad categories in the middle, final fallback last.”

Common Rule Types

DOMAIN exactly matches a complete domain such as api.example.com. DOMAIN-SUFFIX matches a domain and its subdomains and works well for site-wide routing. DOMAIN-KEYWORD matches a string in the domain and is broad enough to cause false positives. IP-CIDR and IP-CIDR6 match IPv4 and IPv6 networks. GEOIP classifies an IP using a geographic database. PROCESS-NAME matches a process name, though availability depends on the OS, permissions, and core support. MATCH handles connections not matched earlier.

rules:
  - DOMAIN,printer.lan,DIRECT
  - DOMAIN-SUFFIX,example.org,Node Select
  - DOMAIN-KEYWORD,example,Node Select
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR6,fd00::/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Node Select

no-resolve tells the core not to perform an extra domain lookup merely to match an IP rule. It suits connections where the destination IP is already known and can avoid unnecessary DNS queries. If matching depends on resolving a domain to an IP, however, this parameter may change the result. Do not append it mechanically; consider the rule type and connection metadata.

Policy Fields Must Reference Existing Groups

The final field of a rule is not an arbitrary label. It must be a proxy-group name, node name, or built-in policy. If the configuration uses Node Select, a group with exactly that name must exist in proxy-groups; characters, spaces, and capitalization must match. DIRECT means a direct connection and REJECT denies the connection. Custom names are fine, but stable short names are easier to maintain across profiles and override files.

Keep Local Exceptions Maintainable

Home NAS devices, printers, router panels, and corporate intranets usually need direct access. List explicit domains first, then cover common private address ranges while preserving local DNS support. Sending every unknown address through a proxy can make LAN access slow or fail. Conversely, an overly broad DIRECT rule may catch destinations that should use a proxy. When adding a rule, copy the actual destination from the connections page instead of guessing from the page title; one page often contacts several APIs, static-resource, and authentication domains.

Rule Sets and Providers

Large rule collections do not belong in the main profile. Cores supporting rule providers can load rule sets from local files or remote URLs and reference them with RULE-SET. Define the behavior type, format, update interval, and local path clearly. When a remote update fails, the core may keep using a cache or may report an error depending on the configuration, so evaluate cache and failure behavior for important rules.

rule-providers:
  private-network:
    type: http
    behavior: ipcidr
    format: yaml
    path: ./ruleset/private-network.yaml
    url: https://example.com/rules/private-network.yaml
    interval: 86400

rules:
  - RULE-SET,private-network,DIRECT
  - MATCH,Node Select

When diagnosing a rule, find the target session on the connections page and record the Host, destination IP, matched rule, and final policy. If the match is unexpected, look for an earlier broad rule. If the rule is correct but the policy is wrong, inspect the current proxy-group selection. If a domain rule never appears, check whether the app uses an IP directly, whether another program handles DNS, or whether the connection is being reused. Reload the profile and create a new connection before testing.

Subscription updates often rewrite rules. For long-term custom rules, prefer the client’s prepend, append, or override mechanisms: place exceptions that must win at the front and ordinary additions before MATCH. Record each rule’s purpose and periodically remove obsolete entries. More rules do not necessarily produce better routing. A maintainable setup explains each rule’s source, priority, and target.

06

TUN AND DNS

TUN Mode: Capture Apps That Ignore the System Proxy

TUN receives IP traffic through a virtual network interface and passes connections to the Clash rule engine. It suits terminal tools, games, some store apps, and software that manages its own connections. Compared with the system proxy, TUN covers more traffic but is more exposed to routing, DNS, firewall, virtual-machine, and other VPN conflicts. Enable it only when the system proxy cannot cover the target application; TUN is not a prerequisite for ordinary browsing.

Basic Requirements Before Enabling It

Windows usually needs a client helper service or administrator privileges to create a virtual interface and modify routes. macOS requires approval for a network extension. Linux needs access to the TUN device and permission to modify routes and firewall rules. When the client offers service mode, confirm that the service installed successfully before enabling TUN. If the switch immediately turns off or logs show permission denied, operation not permitted, or interface-creation errors, investigate permissions and services instead of changing proxy nodes.

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

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

stack selects the TUN network-stack implementation. Common values include system, gvisor, and mixed, though support depends on the core and operating system. system relies more on the OS network stack; gvisor handles more behavior in user space; mixed balances compatibility and performance. If a type of UDP, game, or LAN connection fails, test the stack as one isolated variable. Fully restart the core and clear old connections after each change.

auto-route lets the core add the routes needed for capture. auto-detect-interface identifies the current outbound interface and helps when switching between wired and wireless networks. With multiple interfaces, virtual machines, containers, dial-up connections, or another VPN, automatic detection may choose the wrong interface. Typical symptoms are total loss of connectivity, inaccessible LAN devices, or traffic looping between virtual interfaces. Disable other network-capture tools first, then inspect the system routing table and default interface.

DNS Hijacking and fake-ip

dns-hijack hands DNS queries on selected ports to the core so applications cannot bypass Clash DNS. In fake-ip mode, the resolver returns reserved addresses for domains; the core restores the original domain from its mapping and applies rules. This makes domain matching more consistent, but LAN devices that require real IPs, some games, enterprise authentication, and special protocols may need entries in fake-ip-filter. redir-host returns real resolution results and has different compatibility behavior. Changing the enhanced mode affects caches and existing sessions, so flush system and browser DNS caches before testing.

LAN and Reserved Addresses

With TUN enabled, private ranges, link-local addresses, and local domains must still connect directly. Common IPv4 private ranges include 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16; handle IPv6 local addresses according to the environment. DIRECT rules alone are not enough: if DNS sends an NAS name to an external resolver, the correct address may still be unavailable. Send internal domains to LAN DNS, or define the resolution path explicitly through hosts or nameserver-policy.

Minimal Troubleshooting Steps

If connectivity breaks after enabling TUN, first disable TUN and confirm that the original network returns. Next inspect permission, interface, and route errors in the logs. Then disable other VPN and virtual-interface programs. Test with only essential fields such as enable, stack, auto-route, and auto-detect-interface, and add DNS hijacking and custom routes afterward. If pages work but one game fails, compare TCP, UDP, IPv4, and IPv6 paths instead of discarding the entire configuration.

TUN acceptance testing should cover four areas: a browser follows the expected rules; a terminal without proxy environment variables appears on the connections page; the router or NAS remains reachable; and after TUN is disabled, the system’s default route and DNS recover. Passing all four confirms both the capture and exit paths.

07

OPERATIONS

Maintenance and Troubleshooting: Diagnose by Layer

Reliable operation needs modest but continuous maintenance: keep a working profile, update subscriptions when needed, review client and core release notes, remove obsolete rules, and recheck proxy settings after network changes. Reinstalling the client is rarely the first step because subscription, system proxy, DNS, TUN permissions, and rule errors can survive a reinstall. A better approach is to verify the application, capture, core, policy, and remote-link layers in order.

Build a Repeatable Health Check

After every client or profile update, check that the core starts, the profile loads, and the port is listening. Then test one browser page and one terminal request. The connections page should show the relevant sessions, the rule field should match expectations, and the proxy group should point to the selected policy. Finally test a LAN address to ensure direct exceptions still work. This check is most valuable after major edits, system upgrades, or network changes.

# macOS / Linux: set a proxy for the current terminal
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

# Clear the settings after testing
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
# PowerShell: affects only the current window
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"

# Clear the settings in the current window
Remove-Item Env:HTTP_PROXY
Remove-Item Env:HTTPS_PROXY

Terminal environment variables and the system proxy are independent. If the browser works but the command line does not, check whether the terminal program reads the system proxy, then inspect HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY. Conversely, if the terminal still tries 127.0.0.1:7890 after the client is closed, the environment variables probably remain set. For separate browser and terminal checks, see two diagnostic paths for an ineffective system proxy.

Common Failures and Where to Start

Symptom Check First Next Step
Core cannot start Profile syntax, occupied port, permissions Read the first error and revert the latest change
Browser works, terminal does not Environment variables and app proxy options Explicitly set the local HTTP or SOCKS port
Global works, Rule does not Rule match, DNS, and proxy group Verify the destination and policy on the connections page
Network breaks after TUN starts Service permissions, route conflicts, outbound interface Disable other VPNs and simplify the TUN profile
LAN devices are unreachable Private-network rules and local DNS Add direct ranges and internal-domain resolution
Subscription update fails URL status, system time, response content Separate network, authorization, and parsing failures

Occupied Ports and Leftover Processes

An “address already in use” log entry means another process is listening on the same port. It may be a duplicate core, another proxy client, or a process left behind after an abnormal exit. Identify the owner with the system task manager or a port tool, then close it normally. Changing the port may let the core start, but browsers, terminals, and system proxy settings may still use the old port, creating a new “client works, traffic does not” failure. If you change a port, update every reference to it.

Update Strategy and Rollback

The client, core, subscription, and rule set are four separate update chains. Do not update all of them at once. Save the current profile and client settings, update one layer, and run a basic test. After a core update, focus on field compatibility; after a subscription update, inspect proxy-group names and rule changes; after a rule-set update, inspect matches; after a client update, check the system proxy, service mode, and startup items. When something breaks, rolling back one known layer is safer than rebuilding everything.

After sleep, a network change, or moving from an office network to a home network, old sessions, the default interface, and DNS caches may persist. Restart the core and reopen the target application; if TUN uses automatic interface detection, confirm that the default interface has changed. If only one site fails, clear that site’s sessions and DNS cache instead of resetting the entire network. Good maintenance limits the scope of changes while preserving enough information to explain each one.

08

ADVANCED PATH

Advanced Path: From Working to Maintainable Configuration

After the first seven chapters, the client should have a stable basic path: application traffic enters the core, subscriptions update, Rule routes traffic as expected, TUN is enabled only when needed, and logs and the connections page can locate failures. The advanced stage is not about stacking more features. It is about splitting the configuration into clear, testable, reversible modules. A mature configuration is one that continues working after network changes, subscription updates, and client upgrades—not one with the most rules.

Stage One: Separate Configuration Responsibilities

Keep ports, mode, DNS, proxy groups, and rule entry points in the main profile. Let the service subscription provide nodes and base groups. Use local overrides for fixed custom rules, rule providers for large rule sets, and separate notes for device-specific settings. This prevents subscription updates from overwriting local policies and makes it easier to identify what can move between clients. Profile names can include purpose and environment, such as desktop-rule, laptop-tun, and home-lan, rather than unclear names such as “New Profile 2.”

If the same policy must be maintained across several devices, do not synchronize a complete file containing node credentials. Synchronize only non-sensitive rule fragments, DNS templates, and documentation, then import the subscription separately on each device. This keeps routing logic consistent without overwriting device-specific ports, interfaces, or local paths.

Stage Two: Build DNS Policies by Domain

In complex networks, one nameserver may not suit every domain. Where supported, use nameserver-policy to assign resolvers to internal domains, selected public domains, or different rule sets. Define the problem first: does an internal domain require LAN DNS, do certain domains need protection from incorrect results, or is IPv6 unstable? Without a clear goal, do not stack multiple resolver groups, fallbacks, and filters at once.

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1
    - 8.8.8.8
  nameserver-policy:
    "+.home.arpa":
      - 192.168.1.1
    "+.internal.example":
      - 10.0.0.53
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "+.home.arpa"

Internal DNS addresses must be reachable on the relevant network. A laptop leaving home or the office may time out when using those addresses, so account for network changes. If the client supports profile switching, prepare separate DNS overrides. If one profile must cover every network, ensure internal-domain rules do not affect ordinary public resolution. After changing DNS, verify a specific domain’s result and matched rule rather than relying only on whether a page eventually opens.

Stage Three: Use the Control Interface for Read-Only Diagnosis

The control interface can read the current configuration, proxy groups, and connection state. Listening on a local address is safer by default and sufficient for a desktop client. Before accessing it from a command line, confirm the address and port in external-controller. If a secret is configured, provide authentication as required by the client. Never expose the control interface to a public network. The examples below read the local control port only to confirm that it responds.

curl http://127.0.0.1:9090/configs
curl http://127.0.0.1:9090/proxies
curl http://127.0.0.1:9090/connections

Prefer reading over modifying during diagnosis. /configs can confirm the current mode and some runtime parameters, /proxies shows proxy-group structure, and /connections lists active sessions. Compatible cores may expose different fields, so automation should handle missing fields and unavailable endpoints rather than assuming every client returns the same structure.

Stage Four: Create a Test Checklist for Changes

After changing rules or DNS, test at least four targets: a LAN service that should be direct, a domain that should use a proxy, an unknown destination handled by MATCH, and an application requiring special treatment. Record the target, expected policy, actual rule, and final path. A checklist reveals broad rules, missing DNS policies, and invalid group references more reliably than casually browsing a few sites.

If the profile uses TUN, add an exit test: after disabling TUN, the default route must recover, system DNS must work, and the browser must no longer depend on the local port. With startup enabled, restart the system and check the helper service, core, profile, and system proxy in order. A startup item being enabled does not mean every layer is ready. Log timestamps can show whether the profile loaded before the network came up or whether the system proxy points to a port that is not yet listening.

Further study can follow three directions: for finer routing, explore rule providers, proxy-group chains, and process rules; for broader application coverage, study TUN routes, DNS hijacking, and multiple interfaces; for long-term maintenance, keep profile versions, change notes, and automated syntax checks. Do not pursue all three at once. Start with the clearest problem in the current environment.

Mastery is not memorizing every field. It is being able to explain how a connection enters Clash, why it matches a rule, which policy it finally selects, and which layer to inspect when it fails. To repeat the shortest workflow, return to the quickstart guide. To install or change clients, visit the download center. Keeping quick operations separate from systematic reference makes everyday maintenance more reliable.

Download Client