The Complete Clash Guide from Zero to Advanced Use

1. Core Concepts: Separate the Client, Core, and Subscription

Three Components, Three Different Jobs

The word “Clash” can refer to a graphical client, a proxy core, or a broader set of tools compatible with the Clash configuration format. Separate these roles before you begin: the client provides the window, tray menu, configuration management, and system-permission entry points; the core reads the configuration, listens on local ports, evaluates rules, and creates network connections; the subscription service provides server details, proxy groups, and rule content. Installing a client does not automatically provide usable routes, and importing a subscription does not mean application traffic is already passing through the proxy.

Clash Plus, Clash Verge Rev, FlClash, and Clash Nyanpasu are all graphical clients. A client may bundle a core such as mihomo or let you switch between cores. mihomo is historically related to the former Clash Meta name; it interprets configuration fields, handles DNS, evaluates rules, and runs TUN. Toggles in the interface ultimately become core parameters or operating-system network settings, so the same feature may have a different name or location in each client. Use the generated configuration and core logs as the final reference.

A subscription is a separate source. Its URL normally comes from the service provider you choose; neither this site nor a client project supplies one automatically after installation. A subscription may include nodes, proxy groups, remote rule providers, and DNS settings, or only a basic node list. If the client opens but offers no selectable policies, first check whether the subscription content is complete instead of repeatedly reinstalling the client.

The Basic Path from an App to Its Exit

With a system proxy, an application reads the operating system’s HTTP or SOCKS proxy settings and sends requests to the local port listened to by the client. The core then processes each request according to its mode: rule mode checks rules from top to bottom, and the first match selects DIRECT, REJECT, or a proxy group; global mode usually sends most proxyable traffic to one selected group; direct mode sends supported traffic straight to its destination. TUN mode creates a virtual network interface and intercepts traffic closer to the network layer, but DNS, routing, and rule evaluation still apply.

“The client is running,” “a local port is listening,” “the system proxy is enabled,” “the target app actually uses the system proxy,” and “the rules selected a usable exit” are five separate states. If a browser can open a page, that only proves the browser’s current path works; it does not prove that a terminal, game, or virtual machine uses the same path. Troubleshoot in order: application settings, system proxy, local listening port, core rules, and remote connection. Do not rely on one status indicator on the client’s main screen.

Build a Verifiable Minimal Mental Model

There is no need to edit large amounts of YAML on your first day. Complete one minimal loop: install a client for the platform, import a subscription from a known source, select a configuration and proxy group, enable one traffic-capture method, then verify separately in a browser and a terminal. Study rule coverage, DNS, and TUN only after that loop works; this avoids introducing several variables at once. Apply the same principle to later changes: modify one layer at a time, keep the previous configuration, and record the logs or access results that change.

2. Choose a Client: Decide by Platform and Maintenance Workflow

Choose the Operating Entry Point First, Then Advanced Features

Choose a client based on the operating system, installation method, and maintenance habits—not by treating projects as a simple performance ranking. Beginners can start with Clash Plus, which covers common desktop and mobile platforms and supports subscription management, policy selection, and connection control from a graphical interface. For managing multiple configurations on Windows, macOS, or Linux, compare Clash Verge Rev and FlClash; Windows users can also consider Clash Nyanpasu. Archived clients may still run, but they are a poor choice for environments that depend on ongoing compatibility updates.

On Android, alternatives to Clash Plus include Clash Meta for Android, FlClash, and Surfboard, depending on the device architecture and workflow. Clash Plus is the primary entry point on iOS. Linux desktop users can choose Clash Verge Rev or FlClash; servers, routers, and headless environments are better suited to deploying the mihomo core directly. Use the download page for the complete platform list and current packages, rather than applying desktop-client steps to a command-line core.

Verify the system architecture and package format

Common Windows devices use the x64 architecture, so choose the package that matches the builds actually listed on the download page. On macOS, distinguish Apple Silicon from Intel: open About This Mac and check the chip or processor. Choose an ARM build for Apple silicon and an x64 build for Intel. On Android, confirm ARM64, ARM, or universal support in the device information or a reliable hardware-information page. Most newer devices use ARM64, but the system version alone is not enough to determine this.

Linux also requires a package format that matches the distribution. Debian, Ubuntu, and derivatives generally use .deb; Fedora and RHEL-based systems generally use .rpm. If you use a standalone core archive, prepare the configuration directory, service file, and update process yourself. The difference between a graphical client and a bare core is more than the presence of a window: the former often handles permission requests, system-proxy changes, and core lifecycle management, while the latter requires you to manage the service user, working directory, logs, and restart policy.

Evaluate Features Through the Real Workflow

If you only need a browser and ordinary desktop apps to use the proxy, reliable system-proxy control and subscription updates matter more than elaborate override features. If you need to capture apps that ignore the system proxy, verify the client’s support for TUN, permission installation, and route restoration. If you maintain several subscriptions, check whether configuration switching, overrides, updates, and backups are easy to find. Do not assume that a visible toggle means the current core supports every related field; advanced capability depends jointly on the core version, configuration format, and operating system.

The goal is not to find the client with the most features, but to confirm that the package matches the platform, the common controls are understandable, the subscription is maintainable, and logs are available when something fails. If you are still unsure, read Choosing a Client by Platform and Workflow, then return to the download page to install it.

3. Installation and Permissions: Build a Recoverable Runtime

Desktop Installation Order

Before installation, quit other proxy tools, note the current system-proxy settings, and confirm that the package matches the system architecture. On Windows, the firewall may ask about network access the first time the client runs. Authorize only the network types you actually need; a local proxy listener does not require public inbound access. If the client offers a service mode or helper service, it usually provides the permissions needed to change routes, run TUN, or start with the system. Install it from the client’s built-in entry point rather than obtaining the component from an unknown source.

On macOS, move the app to Applications before launching it for the first time. Running it long-term from the Downloads folder can change path and permission records. The system may show separate prompts for app security, network extensions, VPN configuration, or Keychain access. These correspond to different capabilities: VPN configuration is usually related to TUN or Network Extension; a Keychain prompt may save credentials; a network extension captures traffic. Grant permissions according to the features you plan to use instead of treating every prompt as the same installation error. See the macOS Permissions Guide for details.

After installing a Linux graphical client through the distribution package manager, launch it once from the desktop menu and check whether the log directory is writable. For a .deb file, run the following from its directory:

sudo apt install ./client-package.deb

Replace the filename above with the package name you actually downloaded. The package manager resolves dependencies and is generally easier to use than calling a low-level installation command directly. RPM-based systems should use the package-management command for that distribution. When deploying mihomo without a desktop, do not copy the graphical client’s directory layout; create a separate configuration directory, choose the runtime account, and restrict access to the control port.

System Permissions on Mobile Platforms

Android and iOS usually capture traffic through the system VPN interface. The VPN permission shown on the first connection is required for the operating system to create a virtual network tunnel; it does not verify the subscription. On Android, also review battery optimization and background-activity policies. If the client is stopped after the screen locks, the connection may drop or scheduled updates may fail. Allow the necessary background activity, then test recovery when switching between networks. Do not enable a persistent VPN, per-app routing, and complex DNS overrides all at once.

Some Android systems offer Always-on VPN or a setting that blocks connections outside the VPN. Before enabling these system-wide options, confirm that the client connects reliably in normal mode and know how to disable them. Otherwise, an expired subscription or incorrect DNS configuration may make every app appear offline, while it remains unclear whether the proxy failed or the system policy is still enforcing the tunnel.

Baseline Checks After the First Launch

Do not enable TUN immediately after installation. Open the client log or status page and confirm that the core starts, the configuration directory is readable and writable, and no other process occupies the local listening port. Common listeners include HTTP, SOCKS, and mixed ports; use the values in the current configuration. If the log reports something like “address already in use,” another process owns the port. Close the old proxy or change the port instead of repeatedly clicking Connect.

Next, check how the client exits. Closing the window may only hide it in the tray; use the tray menu for a full exit. Before uninstalling or switching clients, disable the system proxy and TUN, then stop the core. This lets the client restore routes and proxy settings. After an abnormal exit, open the operating system’s network settings to confirm that the proxy address no longer points to the local port and that no virtual network interface remains.

Service Principles for Headless Linux

When running mihomo on a server, first load the configuration in the foreground and read the errors. Only hand it to systemd after it works. The service file should specify the exact executable, working directory, and configuration directory, and use an account with the minimum required permissions. If the configuration enables an external control interface, bind it to the local machine by default; when remote administration is necessary, expose it through a controlled network with access restrictions. For a fuller comparison of desktop and service deployment, see the Linux Deployment Guide.

4. Subscription Configuration: Import, Select, Update, and Override

Importing Only Retrieves the Configuration

A subscription URL usually returns a configuration or node collection that the client can read. In the client’s Configuration, Subscription, or Profiles page, choose Import from URL, paste a known source, and wait for the download and parsing to finish. After a successful import, set that configuration as active and check whether the proxy groups contain selectable options. If a name appears in the list but the core reports an error after switching, inspect the parsing log and identify the exact field; do not equate a successful download with a runnable configuration.

A subscription URL may grant access to private resources and should be treated as sensitive information. Do not post it in public screenshots, shared logs, or discussion threads. For troubleshooting, hide the URL and node credentials while retaining the error field, rule structure, and relevant log lines. If the URL has expired, returns a login page, or is redirected by the network, the client may report a YAML parsing error. Confirm the subscription status through the provider’s management portal instead of editing the failed response at random.

Understand the Main Structure of a Complete Configuration

A typical configuration contains listening ports, operating mode, DNS, nodes, proxy groups, and rules. The following snippet shows their minimal relationships. The server address and authentication data are examples only and cannot be used for a real connection:

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

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

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Example-Node
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,PROXY

mixed-port accepts common HTTP and SOCKS proxy requests; mode: rule enables rule-based evaluation; proxy-groups defines a proxy group named PROXY; the final MATCH rule receives traffic not matched earlier. PROXY is not an exit automatically generated by the core. Removing the group while keeping MATCH creates a reference error. no-resolve tells the core not to resolve a domain proactively just to evaluate that IP rule; it does not disable DNS everywhere.

Separate Remote Content from Local Changes Before Updating

Direct edits to a subscription-generated configuration are usually temporary. On the next update, the client replaces the local copy with the remote content, and manually added rules, DNS settings, or proxy-group options may disappear. For lasting changes, prefer the client’s override, merge, or scripting mechanism. If no reliable override feature exists, save the edited configuration as a separate local file and accept that it will require manual maintenance rather than following subscription updates automatically.

Before updating, record the currently working configuration, proxy-group selections, and important overrides. Afterward, first confirm that the configuration parses, then verify the node list and proxy-group references, and only then restore traffic capture. Do not trigger repeated updates while a connection is failing: server responses, network caches, and client file writes may change simultaneously, making the cause harder to identify. Use a reasonable update interval permitted by the provider.

Validate the Configuration in Three Layers

Syntax validation only shows that YAML can be parsed. Reference validation must also confirm that proxy groups, nodes, and rule targets exist. Runtime validation checks ports, DNS, permissions, and the remote connection. A client can report “configuration valid” while access still fails because it may have completed only the first two layers. After saving changes, reload the configuration and read the first block of the log, addressing the earliest error first. For more common subscription-import issues, browse the Help Center under “Installation and Configuration.”

5. Proxy Modes: The Boundaries of Rules, Global, and Direct

The Mode Determines How the Core Chooses a Destination

Rule, global, and direct modes describe how the core handles traffic that has already entered the proxy chain. They are not the same as the system proxy, TUN, or VPN switch. The system proxy and TUN determine which traffic can enter the core; the operating mode then decides which exit handles it. Switching to global mode does not bring a program that completely ignores the system proxy into the core. Likewise, after enabling TUN, direct mode may still send traffic through the virtual interface and core evaluation before it ultimately exits through the local network.

Rule mode is generally best for everyday use. The core checks destination domains, IPs, ports, or rule sets from top to bottom and normally stops at the first match. A rule can point to DIRECT, REJECT, or a custom proxy group. Rule quality directly affects the result: an overly broad rule placed first can hide more specific rules later, while missing a fallback can make behavior unpredictable across configurations.

Global mode is useful for temporarily testing whether rules cause an access problem or for short periods when a single exit is explicitly required. After switching to global mode, the client usually asks you to select a global group or node. If global mode works but rule mode fails, check which rule matched and whether the group is usable instead of immediately blaming the node. Long-term global mode bypasses the original routing intent and may send local-network or direct-only resources through the wrong exit.

Direct mode can quickly restore local-network access, compare results before and after the proxy, or pause proxy forwarding while leaving the client running. It is not a substitute for exiting the client: the system proxy may still point to the local port, and TUN may still retain its interface and routes; only the core’s choice becomes DIRECT. Before maintenance or uninstallation, disable traffic capture and stop the core instead of merely switching to direct mode.

The System Proxy Works for Apps That Honor Proxy Settings

After enabling the system proxy, the client usually sets the operating system proxy to a loopback address and local port, such as 127.0.0.1:7890. Browsers and some desktop apps read this setting, while terminal programs often require separate environment variables. Some apps have their own proxy options that override the system setting; others use raw network connections and ignore it entirely. If the browser works but the terminal fails, check the terminal environment before switching rule modes.

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

The port must match the client’s current listener. Set variables only for the current terminal session while testing, then decide whether to add them to the shell configuration. With sudo, containers, or remote sessions, environment variables may not be inherited. A loopback address inside a container usually points to the container itself, so do not copy the host address without adjustment.

Use Controlled Comparisons to Locate the Fault

A reliable mode test keeps the node and traffic-capture method unchanged while changing one variable. Record the matched rule in rule mode, then switch to global mode and select the same actual exit. If both fail, check the local port, DNS, node connection, and system time. If only rule mode fails, inspect rule order and the proxy group. If the browser works but the terminal fails, check the application’s proxy settings. For a detailed layered method, see Browser and Terminal Proxy Troubleshooting.

6. Rule-Based Routing: Read Matching and Proxy Groups from Top to Bottom

The First Matching Rule Determines the Result

Rule-based routing is not about the number of rules, but about consistent ordering, match conditions, and policy targets. The core starts at the top and normally stops after a request matches. A broad domain-suffix rule placed first can override a later rule for a specific subdomain; a wide IP rule can also capture an address intended for another proxy group. Arrange custom rules from specific to broad, then let MATCH or an equivalent fallback receive anything unmatched.

rules:
  - DOMAIN,blocked.example,REJECT
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,PROXY

DOMAIN matches a complete domain and suits a single host; DOMAIN-SUFFIX matches the specified domain and its subdomains; IP-CIDR matches an address range; MATCH is the fallback. The example first rejects the specified domain, sends example.org and its subdomains direct, sends private address ranges direct, and gives other requests to PROXY. PROXY must be the name of an existing proxy group. If the actual configuration uses a name such as “Node Selection,” the rule target must use that exact name.

Proxy Groups Turn Rule Results into Selectable Exits

Rules usually point to a proxy group rather than a fixed node. A select group lets you choose manually; other group types may select members by availability or predefined logic, depending on the core. Groups can contain nodes, DIRECT, or other groups, but nesting should remain clear and circular references should be avoided. When renaming a group, check every rule and every other group that references it.

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - AUTO
      - Example-Node
      - DIRECT

  - name: AUTO
    type: url-test
    proxies:
      - Example-Node
      - Backup-Node
    url: https://www.gstatic.com/generate_204
    interval: 300

This example explains the structure and does not imply that every subscription contains the same nodes. url-test checks availability through the specified URL. Its result reflects only that probe target and the network conditions at the time; it cannot replace validation against the real service you need. Very short intervals increase connection and logging overhead. For important traffic, prefer a group whose behavior is easy to understand, and verify which member it ultimately selected when a problem occurs.

DNS Paths Affect Domain and IP Rules

After a domain request enters the core, it can match DOMAIN rules directly. When an app supplies only a destination IP, or a rule needs IP-based evaluation, the addresses produced during DNS resolution and connection setup affect matching. no-resolve prevents an IP rule from proactively triggering a domain lookup for matching. It can reduce unnecessary DNS queries, but it does not disable the configured DNS service. If you also use fake-ip, domain sniffing, or complex DNS routing, understand the complete generated configuration before adding rules.

Handle LAN addresses before broad proxy rules so routers, printers, and local services are not sent to a remote exit. Common private ranges include 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16, but enterprise networks may use additional internal domains and address ranges. Do not copy a public rule set mechanically and assume it fits the current network; add and test the ranges your LAN actually uses.

Remote Rule Sets and Local Rules Have Different Maintenance Costs

Remote rule sets are easy to update centrally, but their reliability depends on the download URL, format, and update policy. Local rules are easier to audit but require manual maintenance. With a remote rule set, check which categories it handles, the default exit, and its behavior when updates fail. With local rules, document each group’s purpose and avoid accumulating duplicates. More rules do not guarantee more accurate routing; stale domains, overlapping ranges, and unreachable rules all increase troubleshooting cost.

Use this safe workflow for rule changes: copy the current configuration, add one specific rule, reload and test its target, and test a target that should remain unaffected. Continue only after both results are correct. If subscription updates overwrite rules, move the change to the client’s override layer and record whether it must appear before or after the remote rule set.

7. TUN Mode: Traffic Capture, DNS, and Route Troubleshooting

TUN Solves the Problem of Getting Traffic into the Core

TUN mode uses a virtual network interface and system routes to capture more IP traffic. It suits apps that ignore the system proxy, some command-line tools, and scenarios requiring unified traffic capture. It does not improve the node’s connection quality or replace rules and proxy groups. After traffic enters TUN, it still passes through DNS resolution, route selection, rule evaluation, and exit connection. If a rule points to DIRECT, the final connection can still be direct. If permissions or configuration are wrong, the impact may be broader than with a system proxy.

Before enabling TUN for the first time, confirm that the subscription, nodes, and basic rules work in system-proxy mode. Then disable other VPNs, proxies, and network filters, and record the current DNS and default route. The client may request a service installation, VPN permission, or network extension; complete these steps through the official interface. After enabling TUN, test a LAN address, a common domain, and an application that ignores the system proxy. Confirm all three paths before enabling startup or Always-on behavior.

What Common Configuration Fields Do

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
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

auto-route makes the core try to add the required routes; auto-detect-interface identifies the current outbound interface; dns-hijack specifies DNS traffic to capture. The available values and behavior of stack depend on the core and platform, so do not switch it blindly without consulting the current client documentation. The public DNS values in the example only illustrate the field structure. Choose actual servers based on reachability, privacy requirements, and the subscription. If the subscription already supplies a complete DNS section, do not layer on an unverified override.

fake-ip returns mapped addresses from a reserved range for domains, then lets the core restore the domain and apply rules. This preserves domain information, but some LAN services, apps that require real addresses, and special protocols may need exclusions. If LAN devices cannot be discovered or an app detects unexpected addresses, check fake-ip filters and direct LAN routing before disabling all DNS features.

Route Conflicts Are More Common Than Node Problems

An enterprise VPN, virtual-machine network, container network, and another proxy can compete for the default route, DNS, or virtual interface. Symptoms include total loss of connectivity after enabling TUN, broken LAN access only, failure after waking from sleep, or traffic continuing to use an old interface after switching Wi-Fi. First disable the other capture tools, turn off TUN, and confirm that the base network recovers. Then run Clash alone. If it works, restore the other tools one at a time and note when the conflict appears.

On Windows, inspect the routing table and network adapters. On macOS, check network services and VPN configuration. On Linux, use system commands to inspect routes and rules. The goal is not to copy every line of output, but to compare the default route, DNS destination, and newly added interfaces before and after enabling TUN. Common Linux checks include:

ip addr
ip route
ip rule
ss -lntup
resolvectl status

Some distributions do not provide every command. ss confirms local listeners; ip route and ip rule show routing; resolvectl suits environments using systemd-resolved. Do not delete route rules in bulk without understanding them. First let the client clean up by disabling it, then restart the network service or system, and only afterward consider manual recovery.

Separate DNS Resolution Failures from Connection Failures

If an IP works but a domain does not, check DNS first. If the domain resolves but the connection fails, continue with rules, exits, and the firewall. Use nslookup, dig, or the system’s built-in resolver to compare system results with the client log. If the log contains no target request at all, the problem may be in the application, system routing, or the path before DNS reaches the core. If the request appears but the policy is wrong, return to the rules and DNS configuration.

Judge TUN stability across startup, shutdown, sleep recovery, network changes, and LAN access. One successful webpage is not enough to prove that route cleanup and DNS restoration work. On mobile devices, test background and lock-screen behavior; on desktops, verify that exiting the client leaves no proxy or route behind.

8. Everyday Maintenance: Updates, Backups, Logs, and Recovery

Update the Client, Core, and Subscription Separately

Client updates, core updates, and subscription updates are three separate change paths. A client update may alter the interface, permission helpers, or configuration storage. A core update may change field support, defaults, or protocol capabilities. A subscription update changes nodes, proxy groups, and rules. Record which layer changed so you can identify regressions; updating all three on the same day makes that difficult. During stable use, back up first, update the subscription, and verify it. Schedule client or core updates as separate tests.

Before updating, save the subscription URL, current policy selections, local overrides, and important custom rules. Copying only the subscription-generated YAML is not enough because overrides, selections, and interface settings may live in other files or databases. Use the client’s export feature when available; otherwise record the information needed to rebuild each layer. Store backups outside the application data directory so uninstalling or clearing the cache does not remove them.

Read Logs Around One Reproducible Action

Useful logs have a clear time window and trigger action. Set the log level to normal informational output, clear the log or note the current time, perform one failed action, and inspect the corresponding lines immediately. Look for configuration loading, DNS queries, rule matches, policy selection, connection setup, and timeouts. Permanently enabling verbose debugging creates a large record and may expose domains or other usage information. Enable it only during troubleshooting, then restore the normal level.

Before sharing logs, remove subscription URLs, authentication fields, control-interface credentials, and node connection details. Keep the error type, destination category, rule name, and necessary context. A screenshot of only the final line may omit the real cause—for example, a connection failure triggered by an earlier DNS error. Address the first anomaly in chronological order, not the later error that appears most often.

Establish a Layered Recovery Order

When the network fails, restore the base network before restoring the proxy. Disable TUN and the system proxy, switch to direct mode or fully exit the client, and confirm that the operating system can resolve and access sites normally. Then start the client without traffic capture and verify configuration loading and the local port. Enable the system proxy and test a browser next; enable TUN last. This sequence separates permission, configuration, node, and routing problems.

If only one site or app fails, do not reinstall immediately. Compare the same destination in direct, rule, and global modes, inspect the matched rule in the log, and check whether the app has its own proxy setting. If every node fails, check the subscription, system time, DNS, and current network restrictions. If only one node fails, try another member of the same group and narrow the issue to that exit. More common answers are available in the Help Center.

Keep a Rollback Point When Cleaning Configurations

As configurations accumulate, duplicate subscriptions, stale overrides, and old rules may interfere with one another. During cleanup, copy the currently working configuration first, then disable suspicious items instead of deleting them immediately. Remove them only after confirming that nothing depends on them. Do not delete the client cache, configuration database, and core directory all at once; doing so destroys both troubleshooting evidence and rollback state. If a reset is necessary, export what matters and validate again from a minimal configuration.

For an archived client, the maintenance priority is migration rather than adding more temporary patches. Choose a client that is still maintained and supports the current platform, import the original subscription, confirm basic connectivity, then migrate local rules and TUN settings. Do not overwrite the old client directory or let two clients control the system proxy or routes simultaneously. After migration, disable the old client’s startup entry and confirm that only one clear capture path remains.

9. Advanced Path: From Using Clash to Diagnosing It Independently

Learn to Read the Configuration Before Building Complex Overrides

The first advanced skill is not collecting more configuration snippets, but understanding the configuration currently in effect. You should be able to locate the listening port, operating mode, DNS, proxy groups, rules, and TUN section, then answer where a request entered, which rule matched, which group handled it, and which exit was finally selected. When the client hides defaults, inspect the exported configuration or core log. Do not edit automatically generated files directly unless you know when they will be overwritten.

The second step is to build a maintainable override layer. Separate LAN direct routing, policies for specific domains, DNS exceptions, and proxy-group changes by purpose, adding one group at a time. Rule names and comments should explain the reason rather than use temporary numbers. After subscription updates, check where merged content is inserted: the same rule at the top or bottom can produce completely different results. If the client supports YAML merging, confirm whether arrays are appended, prepended, or replaced wholesale.

Understand mihomo’s Capabilities and Compatibility Boundaries

mihomo extends the Clash configuration ecosystem with additional protocol, DNS, rule, and runtime capabilities, but individual fields still depend on the current core build and client integration. When migrating an old configuration, run a syntax check with the target core first, then review deprecated fields, rule providers, enhanced DNS modes, and proxy-group behavior. Do not assume that identical file extensions make configurations interchangeable. For background, see Differences Between mihomo and the Original Clash.

Server and router deployments also involve the runtime user, network namespaces, firewall forwarding, and persistent routes. A desktop “Enable TUN” button often performs the permission and routing work for you; a bare core makes the operator responsible for it. Before advanced deployment, verify configuration loading, DNS, and the proxy port in ordinary user space. Add transparent capture and startup services gradually so configuration problems do not become entangled with system-network problems.

Use Minimal Reproduction Instead of Broad Trial and Error

For a complex issue, copy the configuration and reduce it to one entry point, one verifiable node, one proxy group, and a small set of rules. Once the minimal configuration works, restore DNS, rule sets, TUN, and overrides section by section. After each restoration, run the same tests: configuration loading, domain resolution, a direct destination, a proxied destination, a LAN destination, and network recovery after shutdown. This narrows the fault to a specific configuration block.

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

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,DIRECT
  - MATCH,PROXY

This snippet only validates the core structure and local listener; it contains no usable proxy node. Because the PROXY group contains only DIRECT, all fallback traffic ultimately goes direct. Before adding real subscription nodes, confirm that the configuration loads, the port listens, and rule logs are visible. Even if the connection then fails, you can rule out YAML structure and the local port.

Build a Consistent Diagnostic Toolkit

Desktop and server users should know several basic tool categories: inspect listening ports, resolve domains, make HTTP requests, check routes, view processes, and read service logs. Windows offers built-in network commands and PowerShell; macOS and Linux can use curl, dig or nslookup, and netstat or ss. The value of a tool is answering a specific question—“Is 7890 listening?”, “What address does this domain resolve to?”, or “Did the request use the proxy?”—not exporting every system detail at once.

Write down the expected result for every diagnostic test. A LAN address should use DIRECT, a test domain should use a specified proxy group, and closing the client should clear the system proxy. When the actual result differs, inspect the log for that layer. Tests without expectations encourage the vague conclusion that “a webpage opens, so everything is fine,” and can hide traffic that should have been direct but was incorrectly proxied.

Follow a Sustainable Learning Sequence

After completing this manual, continue in the order of configuration structure, rule order, DNS path, TUN routing, and service deployment. Keep one working baseline configuration at every stage and put experiments in a copy. Understand the request path on one machine before studying remote rule sets, complex proxy groups, and transparent routing on routers. Restore the network first; only then enable startup capture.

When the issue concerns platform permissions, return to the installation chapter. When one app does not work, return to the proxy-mode chapter. When traffic takes the wrong exit, return to the rules chapter. When enabling capture breaks the entire network, return to the TUN and DNS chapter. If you only need to establish a basic connection again, open the Quick Tutorial. If you need another client or a fresh package, use the Client Download Page. Layered backtracking preserves evidence and produces more reproducible results than repeated reinstallation.